/*
 * Copyright (c) 2001 Sun Microsystems, Inc.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *       Sun Microsystems, Inc. for Project JXTA."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact Project JXTA at http://www.jxta.org.
 *
 * 5. Products derived from this software may not be called "JXTA",
 *    nor may "JXTA" appear in their name, without prior written
 *    permission of Sun.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 *====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Project JXTA.  For more
 * information on Project JXTA, please see
 * <http://www.jxta.org/>.
 *
 * This license is based on the BSD license adopted by the Apache Foundation.
 *
 * $Id: Keywords.java,v 1.3 2002/03/18 21:00:49 rmjohnson Exp $
 *
 */

package net.jxta.share.metadata;

import net.jxta.document.Element;
import java.util.StringTokenizer;
import java.util.Vector;

/**An implementation of the keywords metadata scheme, where a series of
 * keywords are used as metadata.  The format of a keywords metadata element
 * is as follows:<br><br>
 *
 *<code>&lt;metadata><br>
 *&nbsp;&nbsp;&lt;scheme><br>
 *&nbsp;&nbsp;&nbsp;&nbsp;&lt;name>keywords&lt;/name><br>
 *&nbsp;&nbsp;&nbsp;&nbsp;&lt;location><i>location of resource used to parse 
 * and query the scheme</i>&lt;/location><br>
 *&nbsp;&nbsp;&nbsp;&nbsp;&lt;content-type>text/plain&lt;/content-type><br>
 *&nbsp;&nbsp;&lt;/scheme><br>
 *&nbsp;&nbsp;<i>comma-separated list of keywords</i><br>&lt;/metadata></code>
 *<br><br>
 *For an example of this class in use, see <a href="../../../../../ref/src/net/jxta/test/ShareDemo.java">net.jxta.test.ShareDemo</a> and <a href="../../../../../ref/src/net/jxta/test/SearchDemo.java">net.jxta.test.SearchDemo</a>.
 *
 *@see ContentMetadataFactory
 *@see Description
 *@version $Revision: 1.3 $
 *@author $Author: rmjohnson $
 */
public class Keywords extends ContentMetadata {

    /**The name of the metadata scheme implemented by this class*/
    public static final String SN_KEYWORDS = "keywords";

    /**The content type used by the keywords metadata scheme*/
    public static final String KEYWORDS_CONTENT_TYPE = "text/plain";    

    private String[] keywords;

    /**Create a MetadataQuery instance that can be used to query objects of
     * this class.
     *@param query the keyword to search for
     *@exception IllegalArgumentException if <code>query</code> is null
     */
    public static MetadataQuery newQuery(String query)
	throws IllegalArgumentException {
	if(query == null)
	    throw new IllegalArgumentException();
	return new KeywordQuery(query);
    }

    /**A lightweight MetadataQuery implementation for querying a Keywords
     * object.
     */
    public static class KeywordQuery implements MetadataQuery {
	private String queryString;
	
	/**Create a new KeywordQuery with a given string*/
 	public KeywordQuery(String queryString) {
	    this.queryString = queryString;
	}
	
	/**Use this KeywordQuery to query a Keywords object.
	 *@param metadata the Keywords object to query
	 *@return Integer.MAX_VALUE if the metadata contains a keyword
	 *identical to the query string, Integer.MIN_VALUE if not.
	 *@exception IllegalArgumentException if <code>metadata</code> is not
	 * an instance of the Keywords class.
	 */
	public int queryMetadata(ContentMetadata metadata)
	    throws IllegalArgumentException {
	    String[] keywords;
	    try {
		keywords = ((Keywords)metadata).getKeywords();
	    }catch(ClassCastException cce) {
		throw new IllegalArgumentException("metadata is not of the Keywords class");
	    }
	    for(int a = 0; a < keywords.length; a++) {
		if(keywords[a].indexOf(queryString) != -1)
		    return Integer.MAX_VALUE;
	    }
	    return Integer.MIN_VALUE;
	}
    }

    /**Return the ContentMetadataConstructor used to create instances of this
     * class
     */
    public static ContentMetadataConstructor getConstructor() {
	return new ContentMetadataConstructor() {
		public ContentMetadata newInstance(Element metadataEl)
		throws IllegalArgumentException {
		    return new Keywords(metadataEl);
		}
	    };
    }


    /**Create a Keywords object from a String.
     *@param keywordString a comma-separated list of keywords
     *@exception IllegalArgumentException if keywordString is null
     */
    public Keywords(String keywordString) throws IllegalArgumentException{
	name = SN_KEYWORDS;
	content_type = KEYWORDS_CONTENT_TYPE;
	if(keywordString == null)
	    throw new IllegalArgumentException("null argument");

	//chop up keywordString into keywords
	StringTokenizer st = new StringTokenizer(keywordString, ",");
	int loc = 0;
	Vector keywordVector = new Vector();
	while(st.hasMoreTokens())
	    keywordVector.addElement(st.nextToken());
	keywords = new String[keywordVector.size()];
	keywordVector.toArray(keywords);
    }

    /**Create a Keywords object from an array of keywords.
     *@param keywords an array of keywords to use as metadata
     *@exception IllegalArgumentException - if <code>keywords</code> is null
     * or any of its elements are null or contain a comma ',' character.
     */
    public Keywords(String[] keywords) throws IllegalArgumentException{
	name = SN_KEYWORDS;
	content_type = KEYWORDS_CONTENT_TYPE;
	if(keywords == null)
	    throw new IllegalArgumentException("null argument");
	for(int a = 0; a < keywords.length; a++) {
	    if(keywords[a] == null) {
		throw new IllegalArgumentException("null keyword");
	    } else if(keywords[a].indexOf(',') != -1) {
		throw new IllegalArgumentException("keywords cannot contain commas");
	    }
	}
	this.keywords = keywords;
    }

    /**Create a Keywords object from a &lt;metadata> element.
     *@exception IllegalArgumentException if <code>el</code> is improperly
     * formatted.
     *@exception NullPointerException if <code>el</code> is null.
     */
    public Keywords(Element el) throws IllegalArgumentException {
	init(el);
	name = SN_KEYWORDS;
	content_type = KEYWORDS_CONTENT_TYPE;
	String keywordString = (String)el.getValue();
	if(keywordString == null)
	    throw new IllegalArgumentException("metadata element's value is null");

	//chop up keywordString into keywords
	StringTokenizer st = new StringTokenizer(keywordString, ",");
	int loc = 0;
	Vector keywordVector = new Vector();
	while(st.hasMoreTokens())
	    keywordVector.addElement(st.nextToken());
	keywords = new String[keywordVector.size()];
	keywordVector.toArray(keywords);
    }

/**A function for generating safe copies of this ContentMetadata object.
 *
 * @return a safe copy of this ContentMetadata object
 */
    public Object clone() throws CloneNotSupportedException {
    	String safecp[] = new String[keywords.length];
    	System.arraycopy(keywords, 0, safecp, 0, safecp.length);
    	Keywords result = new Keywords(safecp);
    	result.location = location;
    	return result;
    }
    
    public String getValue() {
	StringBuffer sb = new StringBuffer();
	for(int a = 0; a < keywords.length; a++)
	    sb.append(keywords[a] + ',');
	//get rid of the extra comma
	sb.setLength(sb.length() - 1);
	return sb.toString();
    }

    /**@return the String array representation of the keywords*/
    public String[] getKeywords() {
	return keywords;
    }
}
